package vfs.obj.entity;

import vfs.filter.VFSFilter;
import java.util.Iterator;

/**
 * A VFSEntityFactory provides facilities for creating, restoring, and
 * removing various entities in the virtual folder system.
 * 
 * @author Matthew Eavenson <durandal@uga.edu>
 */
public interface VFSEntityFactory {
    
    /**
     * Creates new user with the specified id.  This
     * method makes a new record in the storage medium.
     * 
     * @param uid the user's id in an external authentication system
     * @param home the user's home directory
     * @return a new user, with the specified id
     */
    VFSUser createUser(String uid, VFSNode home);
    
    /**
     * Creates new group with the specified name.  This
     * method makes a new record in the storage medium.
     * 
     * @param name the group's name
     * @return a new group, with the specified name
     */
    VFSGroup createGroup(String name);
    
    /**
     * Creates new node type with the specified name and description.  
     * This method makes a new record in the storage medium.
     * 
     * @param name the node type's name
     * @param description the node type's description
     * @return a new node type, with the specified name and description
     */
    VFSNodeType createNodeType(String name, String description);
    
    /**
     * Creates new node with the specified properties.  This method makes a 
     * new record in the storage medium.  Can disable the transaction with
     * the given flag.
     * 
     * @param name the node's name
     * @param location the node's reference to an external file or folder
     * @param access the node's public access level
     * @param owner the user that owns the newly created node
     * @param parent the parent node of the newly created node
     * @param transactional determines whether this operation will be transactional
     * @return a new node with the specified properties
     */
    VFSNode createNode(String name, String location, VFSNode.PublicAccess access, VFSUser owner, VFSNode parent, boolean transactional);
    
    /**
     * Creates new node with the specified properties.  This method makes a 
     * new record in the storage medium.  Transactional by default.
     * 
     * @param name the node's name
     * @param location the node's reference to an external file or folder
     * @param access the node's public access level
     * @param owner the user that owns the newly created node
     * @param parent the parent node of the newly created node
     * @return a new node with the specified properties
     */
    VFSNode createNode(String name, String location, VFSNode.PublicAccess access, VFSUser owner, VFSNode parent);
    
    /**
     * Updates a user in the storage medium.
     * 
     * @param user the user to be stored
     */
    void storeUser(VFSUser user);
    
    /**
     * Updates a group in the storage medium.
     * 
     * @param group the group to be stored
     */
    void storeGroup(VFSGroup group);
    
    /**
     * Updates a node type in the storage medium.
     * 
     * @param nodeType the node type to be stored
     */
    void storeNodeType(VFSNodeType nodeType);
    
    /**
     * Updates a node in the storage medium.
     * 
     * @param node the node to be stored
     */
    void storeNode(VFSNode node);
    
    /**
     * Finds users in the system, based on a filter.
     * 
     * @param filter the filter used to find users
     */
    Iterator<VFSUser> findUsers(VFSFilter filter);
    
    /**
     * Finds groups in the system, based on a filter.
     * 
     * @param filter the filter used to find groups
     */
    Iterator<VFSGroup> findGroups(VFSFilter filter);
    
    /**
     * Finds node types in the system, based on a filter.
     * 
     * @param filter the filter used to find node types
     */
    Iterator<VFSNodeType> findNodeTypes(VFSFilter filter);
    
    /**
     * Finds nodes in the system, based on a filter.
     * 
     * @param filter the filter used to find nodes
     */
    Iterator<VFSNode> findNodes(VFSFilter filter);
    
    /**
     * Removes potentially multiple users from the system, based on a filter.
     * 
     * @param filter the filter used to select users for removal
     */
    void removeUser(VFSFilter filter);
    
    /**
     * Removes potentially multiple groups from the system, based on a filter.
     * 
     * @param filter the filter used to select groups for removal
     */
    void removeGroup(VFSFilter filter);
    
    /**
     * Removes potentially multiple node types from the system, based on a filter.
     * 
     * @param filter the filter used to select node types for removal
     */
    void removeNodeType(VFSFilter filter);
    
    /**
     * Removes potentially multiple nodes from the system, based on a filter.
     * 
     * @param filter the filter used to select nodes for removal
     */
    void removeNode(VFSFilter filter);
    
    /**
     * Removes a user from the system.
     * 
     * @param user the user to be removed
     */
    void removeUser(VFSUser user);
    
    /**
     * Removes a group from the system.
     * 
     * @param group the group to be removed
     */
    void removeGroup(VFSGroup group);
    
    /**
     * Removes a node type from the system.
     * 
     * @param nodeType the node type to be removed
     */
    void removeNodeType(VFSNodeType nodeType);
    
    /**
     * Removes a node from the system.
     * 
     * @param node the node to be removed
     */
    void removeNode(VFSNode node);
    
}
